Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ENH: Modify the markups for parameters (x to *x*) #303

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

takanori-pskq
Copy link

Related to numpy/numpy#17714 .

Currently, numpydoc do nothing about the markup for single backticks (`x`). Sphinx seems to interpret `x` as a parameter name (*x*) when the python object x doesn't exists, and a reference (:obj:`x`) otherwise. This process works fine in most cases, but doesn't work if a python object which has the same name as the parameter name exists (see numpy/numpy#17714 (comment) : collision between `size` parameter and numpy.size). So I added a process to convert `x` to *x* for a parameter name x.

@mattip
Copy link
Member

mattip commented Nov 7, 2020

There is a failing test. It would be good to add a test that fails before, passes after this change.

@mattip
Copy link
Member

mattip commented Nov 7, 2020

Is this the same issue in gh-295?

@takanori-pskq
Copy link
Author

I think it's not the same issue, because gh-295 is about whether to convert from `x` to :obj:`x`.

@jnothman
Copy link
Member

jnothman commented Nov 7, 2020 via email

@takanori-pskq
Copy link
Author

Now I changed to use a new config variable numpy_role_param. The default value is None, which means "do nothing". The expected behavier can be achieved by setting numpy_role_param = ':emphasis:'. Later I'll add documents and tests.

@takanori-pskq
Copy link
Author

I noticed that adding a role could break a table structure. In the docstring of numpy.arctan2, with numpy_role_param = ':emphasis:' :

====== ====== ================
:emphasis:`x1`   :emphasis:`x2`   `arctan2(x1,x2)`
====== ====== ================
+/- 0  +0     +/- 0
+/- 0  -0     +/- pi
 > 0   +/-inf +0 / +pi
 < 0   +/-inf -0 / -pi
+/-inf +inf   +/- (pi/4)
+/-inf -inf   +/- (3*pi/4)
====== ====== ================

@jnothman
Copy link
Member

jnothman commented Nov 9, 2020 via email

@jnothman
Copy link
Member

jnothman commented Nov 9, 2020

In fact, I would like to see an example docstrng use case of where this PR is needed.

@takanori-pskq
Copy link
Author

takanori-pskq commented Nov 10, 2020

There are some functions which have size parameter, so `size` appears in some docstrings (For example: polynomial.truncate() ).
These should be interpreted as a parameter (*size* or :emphasis:`size` ), but the existence of the python object numpy.size causes them to be interpreted as the reference.

Base automatically changed from master to main March 5, 2021 12:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants